The Datafile Manager consists of a set of primitives that enable you to store and access data in datafiles on a disk.
Any kind of data can be stored in datafiles, including simple data (integers, strings, booleans, and reals) or complex data (instances and lists) or External datatypes (such as handles, pictures, points, etc.).
The Datafile Manager provides both sequential access and random access to data stored in a datafile.
Datafiles created using the Datafile Manager can be accessed in query (read-only), update (single-user read/write), and share (multi-user read/write) modes. In share mode, individual clusters may be locked, preventing update by more than one user at a time. *471*
Although the Datafile Manager is a lower level of data management system than a relational or object-oriented database manager, either of these two types of systems could be built with the Datafile Manager primitives.
Note that the Datafile Manager primitives are listed and described at the end of this chapter.
Components *472*
The datafiles created by the Datafile Manager are organized into tables, clusters and keys. A datafile contains one or more tables, a table contains any number of clusters, and each table also has a set of keys used to access its clusters.
For example, a sales datafile might have three tables, one for customers, one for products and one for invoices. The customer table would have one cluster for every customer. Each customer cluster contains all the information associated with a customer; name, address, credit rating etc. Likewise for the invoice and product tables, the invoice table would have one cluster for each invoice and the product table would have one cluster for each product. All three of the tables would also have a set of keys. The customer table has a key on customer name, the product table a key on product name and the invoice table a key on invoice number.
Datafiles *472*
A datafile consists of one or more tables. A datafile name is not case sensitive and cannot exceed 26 characters. Two datafiles with the same name cannot be open at the same time even if they reside in separate folders or on different volumes.
A datafile has two files associated with it, one for the data and one for the keys. The name of the key file is composed of the datafile name followed by the word 窶很eys窶.
A datafile is accessed in one of three modes: query, update or share.
o query mode supports fast multi-user read-only access.
o update mode enables single-user read/write access.
o share mode permits multi-user read/write access.
Each mode has restrictions as to which operations may be performed. When using the multi-user modes, all users must be opened in the same mode.
You must open a datafile (using db-open), specifying one of the three modes, prior to accessing information in the datafile. A datafile Path Reference identifier (or datafile ID) is returned by db-open, which can then be used by other Datafile Manager primitives to identify the datafile.
Tables *473*
A table is a collection of clusters and a set of keys. A given datafile may contain one or more tables. Each table has a unique (within the datafile) case-sensitive name (less than 127 characters). Each table may contain an unlimited number of clusters and may have an unlimited number of keys. (Note that a table must have at least one key to enable a program to step through the clusters).
You must open a table to access information in the table. Each time a table is opened, a new access path is constructed. The primitive that opened the table returns a table Path Reference identifier (or table ID) which is then used by other Datafile Manager primitives to identify that table窶冱 access path. Multiple paths can be opened on the same table.
Tables may be used to collect mixed or homomorphic (all of the same kind) sets of objects. When used in database applications, tables are usually used to store homomorphic sets of objects, such as instances of a specific class.
If the information in a table is to be imported from or exported to a non-Prograph application, use only simple data types as the values of attributes. This will allow the table-import and table-export primitives to be used. Simple datatypes include integer, string, boolean, and real. When importing or exporting, each field may have up to 255 characters (and you should call key-first before importing).
Clusters *473*
A cluster is an arbitrary collection of data values. In its simplest form, a cluster is the same as a record. However, a cluster is a much looser form than a traditional record - it is not necessarily of fixed length and is not restricted to being composed of fixed length fields.
Clusters can contain textual, numeric, and/or boolean (TRUE or FALSE) data, as well as External structures (e.g. PICTs and ICONs, etc.) and Prograph objects (instances of classes). (For example, a Products table could include pictures of products).
A Prograph object is converted into a cluster by the Prograph Datafile Manager primitives before it is written into a table. In turn, clusters are converted back into Prograph objects when read from a table.
Every cluster has a unique identifier called the cluster ID. (Cluster ID窶冱 are simply the byte offset of the cluster in the data file.)
Prograph objects stored in a datafile are stored in a form (data cluster) that can be rapidly converted into the equivalent Prograph object structure in memory. This form is larger than would be normally stored in a standard (text string) datafile. If the size of the datafile is an issue, use the to-string primitive to convert Prograph data into a text string, and save the string in the datafile. Use the from-string primitive to convert the text string back to a Prograph data type. This process slows down processing, but generates smaller data files.
Keys *474*
A key is an index into a table. A key enables an application to find a specific cluster. For example, a key on customer name in the customer table would allow you to quickly find customers by name. This is commonly referred to as random access. Keys also enable an application to step through clusters in order.
Since the Datafile Manager does not assign a record number to each cluster, a programmer should create at least one key for each table, to provide a means to step through (i.e. read) the clusters.
Each key has a name which must be unique within a table. Key names are case-sensitive and cannot exceed 127 characters.
A key must be opened in order to use it. Each time a key is opened a new access path is constructed. The primitive opening the key returns a key path reference identifier (key ID). Other datafile primitives can then use the key ID to identify any reference to that key access path. Multiple paths can be opened on the same key.
Each key path also acts as a 窶徘lace holder窶 in a table, tracking at which cluster in the table the user is positioned. You can have multiple key paths open on the same key, and thus several place holders on the same ordering.
Various options can be applied to the values stored in key fields. The following is a list of options that can be applied when creating a key. (Depending on the purpose of a key, the programmer may apply some combination of these options):
boolean key is a boolean (TRUE or FALSE)
integer key is a signed integer (for example, +23, -150)
natural key is a 窶從atural number窶, an unsigned integer data type (for example,
79)
real key is a real number (for example, 2.54)
string key is a string (maximum 255 characters) (default)
ascending clusters are in accessing key order (default)
descending clusters are descending key order
ascii use the ASCII collating sequence
native use the native (Macintosh) collating sequence (default)
sensitive strings are case sensitive
insensitive strings are case insensitive (default)
duplicate multiple clusters with the same key value can exist (default)
unique only one cluster with a particular key value can exist
